---
title: Test Replay
description: Test Replay in Cypress Cloud allows developers to accurately and efficiently debug failed and flaky continuous integration test runs. It captures every test run detail, enabling developers to replay it and inspect the DOM, network requests, console logs, JavaScript errors, and element rendering as they happened in CI.
sidebar_position: 40
---

<ProductHeading product="cloud" />

# Test Replay

:::info

##### <Icon name="question-circle" color="#0097A8" /> What you'll learn

- How Test Replay captures and replays test commands, network requests, console logs, JavaScript errors, and element rendering
- How to view and debug tests with Test Replay in Cypress Cloud

:::

Test Replay in Cypress Cloud allows developers to accurately and efficiently debug failed and flaky [continuous integration](/app/continuous-integration/overview) test runs. It captures every test run detail, enabling developers to replay it and inspect the DOM, network requests, console logs, JavaScript errors, and element rendering as they happened during `cypress run`.

<DocsVideo
  src="https://youtube.com/embed/vFLShoCM8pA"
  title="Test Replay Product Demo"
/>

## Key Benefits

Test failures in CI have historically been captured through screenshots, videos, and stack trace outputs,
but these artifacts provide limited information. Developers often need more context to understand the
root cause of failures, requiring them to reproduce the issue locally, which may not always
be possible due to environmental or network conditions.
This knowledge gap between test failures and debugging capabilities leads to increased debugging
time and potentially deploying unresolved bugs to production. Test Replay solves these problems by providing the following features.

<Icon name="star" color="#69D3A7" /> Time travel to the exact moment of test failure
during runs that happened during Continuous Integration

<Icon name="star" color="#69D3A7" /> Inspect the DOM, network requests, console logs,
JavaScript errors, and element rendering

<Icon name="star" color="#69D3A7" /> Debug failed and flaky test runs with more context
and accuracy

<Icon name="star" color="#69D3A7" /> Eliminate the need to reproduce test failures
locally

<Icon name="star" color="#69D3A7" /> Shareable and collaborative debugging experience

Test Replay complements the existing visual artifacts provided by Cypress Cloud. It eliminates the need for
local test replication by enabling developers to time-travel to the exact moment of test failure.
Developers gain access to previously inaccessible details and feedback loops, enabling
faster and more accurate debugging, and instilling confidence in handling test failures in CI.
Replacing video recordings with Test Replay provides a superior debugging experience that is
sharable and supports team collaboration with efficient workflows.

<DocsVideo
  src="https://youtube.com/embed/hX9Br8QSYgc"
  title="Unlocking the Power of Test Replay!"
/>

## Get Started

:::success

Test Replay is available to **all** Cypress Cloud plans
at no additional cost, subject to usage limits.

<CloudFreePlan />

:::

### 1. Record Test Runs

All you need to do is [record test runs](/cloud/get-started/setup) and log in to your Cypress Cloud
account to leverage Test Replay's debugging capabilities. No additional configuration
or changes to your existing tests are required.

### 2. Access Test Replay

Accessing the replay of your test is as simple as reviewing any other test artifact in Cypress Cloud.

Hover on a [test for review](/cloud/features/recorded-runs#Tests-for-Review) under a run's **Overview**.

<DocsImage
  src="/img/cloud/features/test-replay/replay_row_magnified.jpg"
  alt="Run overview row"
/>

Or navigate to the [test detail sidebar](/cloud/features/recorded-runs#Test-detail-sidebar) header or above each attempt in the errors panel. The header option will replay the first failing test while the option above each attempt will replay the affiliated test.

<DocsImage
  src="/img/cloud/features/test-replay/replay_sidebar_magnified.jpg"
  alt="Run sidebar"
  width="60%"
/>

### 3. Debug With Test Replay

Both options above display the Test Replay interface, which we'll unpack from top to bottom in more detail below.

#### Run header

The left side of the header displays the Cypress Cloud test run ID number (#), with the Git branch name along with the spec, platform and browser information. Hovering on this exposes additional test metadata.

<DocsImage
  src="/img/cloud/features/test-replay/test-replay-header.jpg"
  alt="Test Replay header"
/>

#### Command Log

The left side of the screen displays the [command log](/app/core-concepts/open-mode#Command-Log) just like in the Cypress app, where you can step through, inspect and [time travel](/app/core-concepts/open-mode#Time-traveling) debug your test.

<DocsImage
  src="/img/cloud/features/test-replay/command-log.png"
  alt="Test Replay Developer Tools panel"
  width="60%"
/>

#### Developer Tools

Dive into network-level traffic, console events and inspect the application under test just as you can in the browser.

<DocsImage
  src="/img/cloud/features/test-replay/dev-tools.png"
  alt="Test Replay Developer Tools panel"
  width="60%"
/>

#### Replay Controls

Toggle each test attempt, play back errors at a variety of speeds or scrub through the captured error by dragging the playhead along the timeline.

<DocsImage
  src="/img/cloud/features/test-replay/scrubber.png"
  alt="Test Replay scrubber controls"
/>

## How Test Replay Works

Our aim is to create an impactful debugging experience that covers the most ground for users.
Cypress captures a wide range of data during end-to-end and component test runs.
This data is then uploaded and stored in Cypress Cloud and replayed for debugging through Test Replay.

### What is captured

- Test commands
- Network requests
- Console logs
- JavaScript errors
- Element rendering
- DOM mutations
- CSS styles
- SVG elements
- Iframes
- Shadow DOM
- Canvas elements (v13.5.0+, please contact us at support@cypress.io to enable capturing canvas elements)

### What is not captured

Currently Test Replay does not support the following:

- Tests recorded in Cypress App below v13.
- WebKit browser (Safari) tests ([see issue](https://github.com/cypress-io/cypress/issues/28895))
- Firefox browser tests ([see issue](https://github.com/cypress-io/cypress/issues/28894))
- Video elements ([see issue](https://github.com/cypress-io/cypress/issues/29903))
- Audio elements ([see issue](https://github.com/cypress-io/cypress/issues/29905))
- Objects that do not have `type="image/svg+xml"` ([see issue](https://github.com/cypress-io/cypress/issues/29904))
- Shadow DOM elements with `slotAssignment="manual"` ([see issue](https://github.com/cypress-io/cypress/issues/29107))
- Shadow DOM canvases ([see issue](https://github.com/cypress-io/cypress/issues/30438))
- Server sent events ([see issue](https://github.com/cypress-io/cypress/issues/29908))
- Web sockets ([see issue](https://github.com/cypress-io/cypress/issues/29907))
- `localStorage` & `sessionStorage` ([see issue](https://github.com/cypress-io/cypress/issues/29909))
- Cookies ([see issue](https://github.com/cypress-io/cypress/issues/29910))
- Network traffic from `cy.request()` ([see issue](https://github.com/cypress-io/cypress/issues/30575))
- Console props of Cypress commands outside of `cy.request()` ([see issue](https://github.com/cypress-io/cypress/issues/29911))

### Performance

#### Recording

Capturing this additional data can use additional resources while recording, but you can
expect an even performance exchange with Test Replay versus video recording.
There is more activity to capture Test Replay data but without the overhead of recording,
compressing, and storing video assets.

:::info

**Tip:** We recommend disabling video recording when recording with
Test Replay enabled to optimize performance.

:::

You can inspect the size of the Test Replay data that is uploaded to the Cloud
and the time spent uploading the Test Replay data by inspecting the standard output of the test run.

The only assets stored to your file system are in a temporary directory and deleted after the run.

```shell
  (Uploading Cloud Artifacts)

  - Video - Nothing to upload
  - Screenshot - Nothing to upload
  - Test Replay - 298 kB

  Uploading Cloud Artifacts: .

  (Uploaded Cloud Artifacts)

  - Test Replay - Done Uploading 298 kB in 633.40ms 1/1
```

#### Canvas Elements

Capturing canvas elements can be resource-intensive. If you have a large number of canvas elements or large canvas elements
in your application, you may experience performance issues when capturing Test Replay, so we recommend
monitoring the performance of your tests after enabling capturing of canvas elements and raising any issues with us.

Capturing canvas is disabled by default. To enable capturing canvas elements, please contact us at support@cypress.io.

### Runner UI

The Cypress App ["Runner UI"](/app/core-concepts/open-mode#Test-Runner) is made up of a
[command log](/app/core-concepts/open-mode#Command-Log) which displays every command
executed in your spec. The UI also includes the URL bar, browser selector, and the viewport size
control above the application under test.

The Runner UI is visible during `cypress open` mode, but is also rendered
([headless](/app/references/command-line#Options)-ly) during `cypress run` so that it displays
within captured screenshots or videos, to assist in debugging CI failures.

But rendering the Runner UI while running tests via `cypress run` can have performance implications,
resulting in a slower test runtime, especially on lower resourced machines.

With Test Replay, Cypress Cloud regenerates the entire UI for viewing the run and debugging CI failures.
Additionally, displaying the Cypress command log in videos and screenshots is less valuable for users
using Test Replay.

So when Test Replay is enabled, the Runner UI does not render during `cypress run`

If you'd like to render the Runner UI, you can turn on this behavior by passing `--runner-ui` as a CLI flag.
You may encounter a slower performance when turning this on, especially in lower resourced machines.
Learn more about the `--runner-ui` [command line option](/app/references/command-line#cypress-run-runner-ui).

## Opt-out of Test Replay

:::caution

Please refer to the [Cypress Cloud Terms of Use](https://cloud.cypress.io/terms-of-use) and our [Security & Compliance](https://www.cypress.io/security/) guide for specifics around reasonable use of Cypress Cloud, data storage and security at Cypress.

Test Replays, including the test data leveraged within your tests, are visible to everyone with access to your project.

:::

If you do not want to capture test data for replay and debugging purposes, you can "shut off" Test Replay in project settings.

<DocsImage
  src="/img/cloud/features/test-replay/opt-out.png"
  alt="Test Replay opt-out controls"
/>

## Troubleshooting

:::info

**Tip:** Before troubleshooting further, please ensure you're using the latest version of Cypress. We fix bugs with Test Replay often,
so your issue may already be fixed.

:::

If you're experiencing an issue and have already tried the troubleshooting steps below,
you can report an issue within the Test Replay window in the Cloud by clicking the **Report an Issue** button.

<DocsImage
  src="/img/cloud/features/test-replay/report-issue.png"
  alt="Screenshot of top right corner of Test Replay window with a button that says 'Report an Issue'"
/>

### Test Replay is not available

If the Test Replay button is disabled in Cypress Cloud, there are a few things to check:

1. Confirm runs have been recorded to Cypress Cloud using Cypress `v13` or later.
2. Ensure tests were recorded using a Chromium-based browser (Chrome, Edge, Electron).
3. Check that Test Replay is enabled in Cypress Cloud project settings.
4. Review the standard output of the test run to ensure there was not an [error uploading Test Replay](#Test-Replay-errored-during-upload).

**Safari 16.3 and under users may experience errors when _viewing_ Test Replay**

Cypress Cloud relies on certain web APIs implemented by specific browsers. Safari versions older than 16.4 may be missing certain APIs required for rendering Test Replay. To view Test Replay in Safari, version 16.4 and above may be used. This does not affect running tests or recording to Cypress Cloud.

### Test Replay errored during upload

Sometimes, tracking down issues that prevent uploading Test Replay recordings can be difficult.
We try to provide as much detail with our error messaging as possible to resolve the issue.

Specs that have problems uploading a Test Replay recording may have a disabled "Test Replay" button in Cypress Cloud.

<DocsImage
  src="/img/cloud/features/test-replay/error-uploading-test-replay.png"
  alt="Popover in Cypress Cloud on hover of disabled Test Replay button that reads 'There was an error uploading the Test Replay for this test. Learn more.'"
/>

The exact error message can be seen by viewing the spec's output.

<DocsImage
  src="/img/cloud/features/test-replay/view-spec-output.png"
  alt="Spec row in Cypress Cloud showing number of passed tests, run time, group, test type, OS, browser, and a button that says 'View Output' which is higlighted with an arrow and rectangle"
/>

#### Common errors

- **Failed to upload after X attempts error**: This error occurs when the Test Replay data is not uploaded to the Cloud
  due to network issues. This could be due to a poor network connection or a network issue. To fix:
  - Try recording the test again to see if the issue persists.
- **Network or HTTP error**: These errors indicate that Cypress could not establish a connection to upload. To fix:
  - Ensure the machine has access to the internet.
  - Ensure that the network configuration of the machine recording the spec allows for [Cypress URLs](/app/references/troubleshooting#Allow-Cypress-URLs-on-VPNs).
  - Check if a firewall or proxy is blocking the connection. If a proxy is blocking connections, configure the proxy so that it does not block uploads to Cypress URLs.
  - Check [cypress status](https://www.cypressstatus.com/) for any ongoing issues.
- **Invalid or missing Test Replay upload URL**: Specs that take longer than the
  [run timeout](/cloud/account-management/projects#Run-Timeout) will not successfully upload. To fix:
  - Reduce the run time of the spec.
  - Or increase the run timeout in the project settings.

## See also

- [Test Replay FAQ](/cloud/faq#Test-Replay)
- [Cypress v13 changelog](/app/references/changelog#13-0-0)
- [Cypress Default Video Configuration](/app/references/configuration#Videos)
- [Cypress Video Artifacts](/app/guides/screenshots-and-videos#Videos)
